Configuring Optional Signatures

  Signature fullnameOptionalSignature = SignatureBuilder.signatureFor("[email protected]")   .onPage(0)   .atPosition(100, 100)   .makeOptional()   .build();  

  Signature captureOptionalSignature = SignatureBuilder.captureFor("[email protected]")   .onPage(0)   .atPosition(100, 200)   .makeOptional()   .build();   Signature initialsOptionalSignature = SignatureBuilder.initialsFor("[email protected]")   .onPage(0)   .atPosition(100, 300)   .makeOptional()   .build();   Signature mobileOptionalSignature = SignatureBuilder.mobileCaptureFor("[email protected]")   .onPage(0)   .atPosition(100, 400)   .makeOptional()   .build();  

  [Signer.SigStyle#.Optional]  

  {{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}  

To download the full code sample see our Code Share site.

Optional Signatures give your signers the flexibility to complete a transaction without having them sign all the signature fields in their documents. This feature is useful for documents that require the signer to either accept or decline sections of a form.

Note: At least one signer must have either a required signature or a separate Accept Only document for a transaction to be completed. This does not include the default consent form.

Creating Optional Signatures

The following code will make the Signature object optional:

  Signature fullnameOptionalSignature = SignatureBuilder.SignatureFor("[email protected]")   .OnPage(0)   .AtPosition(100, 100)   .MakeOptional()   .Build();  

Similarly, the MakeOptional() function is also available for other signature types:

  Signature captureOptionalSignature = SignatureBuilder.CaptureFor("[email protected]")   .OnPage(0)   .AtPosition(100, 200)   .MakeOptional()   .Build();   Signature initialsOptionalSignature = SignatureBuilder.InitialsFor("[email protected]")   .OnPage(0)   .AtPosition(100, 300)   .MakeOptional()   .Build();   Signature mobileOptionalSignature = SignatureBuilder.MobileCaptureFor("[email protected]")   .OnPage(0)   .AtPosition(100, 400)   .MakeOptional()   .Build();  

Results

Any signature that has been denoted as being optional will be clearly indicated as such. Optional signatures do not have to be signed in order to confirm a transaction.

Creating Optional Signatures With Document Extraction

To make a signature field optional, apply the following format to your PDF form:

  [Signer.SigStyle#.Optional]  

The last .Optional part is extended in order to set the signature as optional. Here are a few more examples:

 

• Signatures are by default required, so only add .Optional when necessary.
• PDF form name syntax is case insensitive, including the Role Name and Custom ID of the signer.[Agent1.Fullname1.Optional] is treated the same as [AGENT1.FULLNAME1.OPTIONAL].
• This syntax extension is only available for signatures and will not be recognized when creating any other fields. Names like [Agent1.Fullname1.Textfield1.Optional] will not work.

Once the transaction is created, all signatures should appear as expected.

Creating Optional Signatures With Text Tags Extraction

The following line demonstrates the syntax of a Text Tag:

  {{Xesl[_fieldName]:roleName:fieldType[:parameter1,parameter2,...]}}  

To mark this signature as optional, change the third character, X, to a question mark, ?. Otherwise, all signatures will be required by default. Here are some examples:

In this example, {{?esl:Signer1:Signature}} means an Optional Fullname Signature is bound to Signer1.

To download the full code sample see our Code Share site.

Optional Signatures give your signers the flexibility to complete a transaction without having them sign all the signature fields in their documents. This feature is useful for documents that require the signer to either accept or decline sections of a form.

Note: At least one signer must have either a required signature or a separate Accept Only document for a transaction to be completed. This does not include the default consent form.

Creating Optional Signatures

The following code will make the Signature object optional:

If you need a comparison to the basic object creation procedure, or if this is the first time creating a transaction, see Creating and Sending a Transaction.

HTTP Request

POST /api/packages

HTTP Headers

Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key 

Request Payload

 -- -- --WebKitFormBoundary1bNO60n7FqP5WO4t Content - Disposition: form - data;
name = "file";
filename = "optional signature basic usage.pdf"
Content - Type: application / pdf % PDF - 1.5 % µµµµ 1 0 obj < >>> endobj....-- -- --WebKitFormBoundary1bNO60n7FqP5WO4t Content - Disposition: form - data;
name = "payload" {
   "documents": [{
      "approvals": [{
         "fields": [{
            "height": 50,
            "left": 100,
            "page": 0,
            "subtype": "FULLNAME",
            "top": 100,
            "type": "SIGNATURE",
            "width": 200
         }],
         "id": "signature1",
         "role": "Role1"
      }, {
         "fields": [{
            "height": 50,
            "left": 100,
            "page": 0,
            "subtype": "FULLNAME",
            "top": 300,
            "type": "SIGNATURE",
            "width": 200
         }],
         "id": "signature2",
         "role": "Role1",
         "optional": true
      }],
      "name": "Test Document"
   }],
   "name": "Optional Signature Basic Usage REST",
   "roles": [{
      "id": "Role1",
      "signers": [{
         "email": "[email protected]",
         "firstName": "1.firstname",
         "lastName": "1.lastname",
         "company": "OneSpan Sign"
      }]
   }],
   "type": "PACKAGE",
   "status": "SENT"
}-- -- --WebKitFormBoundary1bNO60n7FqP5WO4t--

For a complete description of each field, see the Request Payload table below.

Response Payload

 {   "id": "7g-LhL0zEzN0jZi7Yccell7y6jA="   } 

Results

Any signature that has been denoted as being optional will be clearly indicated as such. Optional signatures do not have to be signed in order to confirm a transaction.

Creating Optional Signatures With Document Extraction

To make a signature field optional, apply the following format to your PDF form:

  [Signer.SigStyle#.Optional]  

The last .Optional part is extended in order to set the signature as optional. Here are a few more examples:

 

• Signatures are by default required, so only add .Optional when necessary.
• PDF form name syntax is case insensitive, including the Role Name and Custom ID of the signer.[Agent1.Fullname1.Optional] is treated the same as [AGENT1.FULLNAME1.OPTIONAL].
• This syntax extension is only available for signatures and will not be recognized when creating any other fields. Names like [Agent1.Fullname1.Textfield1.Optional] will not work.